---
title: Toast | gluestack-ui | Installation, Usage, and API

description: Toast is a component that can display alerts, notifications, or messages on top of an overlay layer. It is commonly used to inform users of important information or actions.

pageTitle: Toast

pageDescription: Toast is a component that can display alerts, notifications, or messages on top of an overlay layer. It is commonly used to inform users of important information or actions.

showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="ui/Components/Feedback/Toast" />

import {
  Toast,
  ToastTitle,
  ToastDescription,
  useToast,
  Icon,
  CloseIcon,
  VStack,
} from './Toast';
import { CheckIcon, MessageCircle } from './Toast';
import {
  AlertTriangleIcon,
  Button,
  ButtonText,
  Pressable,
  Center,
} from './Toast';
import { transformedCode } from '../../../utils';
import {
  AppProvider,
  CodePreview,
  Table,
  TableContainer,
  Text,
  InlineCode,
} from '@gluestack/design-system';

import { View } from 'react-native';

import Wrapper from '../../Wrapper';

This is an illustration of a **Themed Toast** component with default configuration.

<AppProvider>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={true}
    metaData={{
      code: `
      function Example() {
          const toast = useToast();
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement:"top",
                  render: ({ id }) => {
                    const toastId = "toast-" + id;
                    return (
                       <Toast nativeID={toastId} {...props}>
                       <VStack space="xs" flex={1}>
                        <ToastTitle>New Message</ToastTitle>
                        <ToastDescription >
                          Hey, just wanted to touch base and see how you're doing. Let's catch up soon!
                        </ToastDescription>
                         </VStack>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        View,
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Text,
        Button,
        ButtonText,
        VStack,
      },
      argsType: {
        action: {
          control: 'select',
          options: ['success', 'info', 'error', 'warning', 'attention'],
          default: 'attention',
        },
        variant: {
          control: 'select',
          options: ['accent', 'solid', 'outline'],
          default: 'solid',
        },
      },
    }}
  />
</AppProvider>

<br />

## API Reference

### Import

To use this component in your project, include the following import statement in your file.

```jsx
import { useToast, Toast } from '@gluestack-ui/themed';
```

### Anatomy

The structure provided below can help you identify and understand a Toast component's various parts.

```jsx
export default () => (
  <Toast>
    <ToastTitle />
    <ToastDescription />
  </Toast>
);
```

### Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

#### toast.show
The following props can be passed while calling `toast.show`.

<AppProvider>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Type</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>duration</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>number or null</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>5000</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`The delay before the toast hides (in milliseconds). If set to null, toast will never dismiss.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>onCloseComplete</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`()=>{}`}</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Callback function to run side effects after the toast has closed.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>placement</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              'top'| 'top right' | 'top left' | 'bottom' | 'bottom left' |
              'bottom right'
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bottom</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>Position of toast on the web page.</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>render?: (props: any)</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>ReactNode</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>Renders a toast component</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>avoidKeyboard</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>bool</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>false</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`If true and the keyboard is opened, the Toast will move up equivalent to the keyboard height.`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>containerStyle</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>ViewStyle</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>-</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>Container style object for the toast.</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</AppProvider>

**Descendants Styling Props**
Props to style child components.

<AppProvider>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Sx Prop</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Description</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>_icon</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Prop to style Icon Component`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>_title</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Prop to style AlertTitle Component`}</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>_description</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>{`Prop to style AlertDescription Component`}</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</AppProvider>

#### ToastTitle

Contains all Text related layout style props and actions.
It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

#### ToastDescription

Contains all Text related layout style props and actions.
It inherits all the properties of React Native's [Text](https://reactnative.dev/docs/text) component.

### Accessibility

We have outlined the various features that ensure the Toast component is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the [WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/).

#### Keyboard

- `Tab + Enter`: Triggers the toast's action.

#### Screen Reader

- VoiceOver: When the toast is focused, the screen reader will announce the toast's title.

## Themed

The themed version of the component is a pre-styled version of the component, which allows you to quickly integrate the component into your project. The component's design and functionality are fully defined, allowing you to focus on the more important aspects of your project. To know more about Themed Library please visit this [link](https://gluestack.io/ui/docs/core-concepts/themed-library).

### Props

Toast component is created using View component from react-native. It extends all the props supported by [React Native View](https://reactnative.dev/docs/view#props), [utility props](/ui/docs/styling/utility-and-sx-props) and the props mentioned below.

#### Toast

<AppProvider>
  <TableContainer>
    <Table>
      <Table.THead>
        <Table.TR>
          <Table.TH>
            <Table.TText>Name</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Value</Table.TText>
          </Table.TH>
          <Table.TH>
            <Table.TText>Default</Table.TText>
          </Table.TH>
        </Table.TR>
      </Table.THead>
      <Table.TBody>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>action</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>
              error | warning | success | info | attention
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>attention</Table.TText>
          </Table.TD>
        </Table.TR>
        <Table.TR>
          <Table.TD>
            <Table.TText>
              <InlineCode>variant</InlineCode>
            </Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>solid | outline | accent</Table.TText>
          </Table.TD>
          <Table.TD>
            <Table.TText>solid</Table.TText>
          </Table.TD>
        </Table.TR>
      </Table.TBody>
    </Table>
  </TableContainer>
</AppProvider>

> Note: These props are exclusively applicable when utilizing the default configuration of gluestack-ui/config. If you are using a custom theme, these props may not be available.

### Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

#### Toast with actions

A versatile Toast component with customizable actions, enabling users to take various actions directly from the notification popup for enhanced usability and convenience.

<AppProvider>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={false}
    metaData={{
      code: `
        function Example() {
          const toast = useToast();
          const toastActions = [
            {
              actionType: 'info',
              title: 'Info',
              description: 'Your order has been received and is being processed. You will receive a confirmation email shortly.',
            },
            {
              actionType: 'success',
              title: 'Success!',
              description: 'Your changes have been saved successfully.',
            },
            {
              actionType: 'warning',
              title: 'Warning!',
              description: 'Your account subscription will expire in 5 days. Please renew your subscription to avoid interruption of service.',
            },
            {
              actionType: 'error',
              title: 'Error!',
              description: 'There was an error processing your request. Please try again later.',
            },
            {
              actionType: 'attention',
              title: 'Attention!',
              description: 'Please review and accept our updated terms and conditions before continuing to use the application.',
            },
          ];
          return (
            <Center h='$80'>
              <VStack space='md'>
                {
                  toastActions.map((action, index)=>{
                    return (
                      <Button
                        key={index}
                        onPress={() => {
                          toast.show({
                            placement:"top",
                            render: ({ id }) => {
                              const toastId = "toast-" + id;
                              return (
                                <Toast nativeID={toastId} action={action.actionType}>
                                  <VStack space="xs" flex={1}>
                                    <ToastTitle>{action.title}</ToastTitle>
                                    <ToastDescription >
                                    {action.description}
                                    </ToastDescription>
                                  </VStack>
                                </Toast>
                              );
                            },
                          });
                        }}
                      >
                        <ButtonText>{action.actionType}</ButtonText>
                      </Button>
                    )
                  })
                }
              </VStack>
            </Center>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        View,
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Text,
        Button,
        ButtonText,
        VStack,
        Center,
      },
      argsType: {},
    }}
  />
</AppProvider>

#### Toast with variants

A versatile Toast component with multiple variants, offering different styles and visual cues to effectively convey various types of notifications and feedback to users.

<AppProvider>
  <CodePreview
    _rendererWrapper={{ px: '$2.5' }}
    showComponentRenderer={true}
    showArgsController={true}
    metaData={{
      code: `
      function Example() {
          const toast = useToast();
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement:"top",
                  render: ({ id }) => {
                       const toastId = "toast-" + id;
                        return (
                        <Toast nativeID={toastId} {...props} action='success'>
                       <VStack space="xs" flex={1}>
                        <ToastTitle>Attention!</ToastTitle>
                        <ToastDescription >
                        Please review and accept our updated terms and conditions before continuing to use the application.
                        </ToastDescription>
                         </VStack>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        View,
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Text,
        Button,
        ButtonText,
        VStack,
      },
      argsType: {
        variant: {
          control: 'select',
          options: ['accent', 'solid', 'outline'],
          default: 'solid',
        },
      },
    }}
  />
</AppProvider>

#### Toast with placement

A Toast component with different placement options allows for the flexible positioning of toast notifications, enabling them to appear in various locations within a user interface, enhancing user visibility and providing a customizable approach to displaying temporary messages or alerts.

<AppProvider>
  <CodePreview
    metaData={{
      code: `
        function Example() {
          const toast = useToast();
          const placements = {
            'bottom': 'Looks like you found the hiding spot at the bottom of the page!',
            'top': 'The top spot is your favorite hiding spot! Keep hunting for success.',
            'top right': "You\'re hiding in plain sight at the top right corner! You are good at this game.",
            'top left': "You\'re a master of disguise hiding in the top left corner! Keep up the sneakiness.",
            'bottom left': "You\'re not the best at hiding, but we found you in the bottom left corner.",
            'bottom right': "Found you! Don\'t worry, we wont tell anyone.",
          }
          const {...props}
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement: placement,
                  render: ({ id }) => {
                      const toastId = "toast-" + id;
                      return (
                        <Toast nativeID={toastId}>
                        <ToastDescription>{placements[placement]}</ToastDescription>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        View,
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Text,
        Button,
        ButtonText,
      },
      argsType: {
        placement: {
          control: 'select',
          options: [
            'bottom',
            'top',
            'top right',
            'top left',
            'bottom left',
            'bottom right',
          ],
          default: 'bottom',
        },
      },
    }}
  />
</AppProvider>

#### Dismissable Toast

A dismissable Toast component offers users the ability to dismiss or close the toast notification, providing control and convenience in managing temporary messages or alerts within a user interface.

<AppProvider>
  <CodePreview
    showArgsController={false}
    metaData={{
      code: `
        function Example() {
          const toast = useToast();
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement: 'top',
                  render: ({ id }) => {
                    const toastId = "toast-" + id;
                    return (
                      <Toast bg='$success700' nativeID={toastId}>
                        <Icon as={CheckIcon} color='$white' mt='$1' mr='$3' />
                        <VStack space='xs' flex={1}>
                        <ToastTitle color='$textLight50' >Download Complete</ToastTitle>
                        <ToastDescription color='$textLight50'>Your file 'wadewarren.docx' has been downloaded successfully. You can find it in your Downloads folder.</ToastDescription>
                        </VStack>
                       <Pressable mt='$1' onPress={() => toast.close(id)}>
                        <Icon as={CloseIcon} color='$coolGray50' />
                       </Pressable>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        View,
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Text,
        Icon,
        CloseIcon,
        VStack,
        CheckIcon,
        Button,
        ButtonText,
        Pressable,
      },
      argsType: {},
    }}
  />
</AppProvider>

#### Toast custom duration

A Toast component with custom duration allows for specifying the length of time the toast notification remains visible, offering flexibility in controlling the duration of temporary messages or alerts within a user interface.

<AppProvider>
  <CodePreview
    metaData={{
      code: `
        function Example() {
          const toast = useToast();
          const {...props}
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement: 'top',
                  duration: duration,
                  render: ({ id }) => {
                    const toastId = "toast-" + id;
                    return (
                      <Toast bg='$secondary700' nativeID={toastId} p='$3'>
                        <Icon as={MessageCircle}  color='$white' mt='$1' mr='$3' />
                        <VStack space='xs' flex={1}>
                        <ToastTitle color='$textLight50'>New Message</ToastTitle>
                        <ToastDescription color='$textLight50'>Hey, just wanted to touch base and see how you're doing. Let's catch up soon!</ToastDescription>
                        </VStack>
                         <Pressable mt='$1' onPress={() => toast.close(id)}>
                        <Icon as={CloseIcon} color='$coolGray50' />
                       </Pressable>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        View,
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Text,
        Button,
        ButtonText,
        Pressable,
        Icon,
        CloseIcon,
        VStack,
        MessageCircle,
      },
      argsType: {
        duration: {
          control: 'input',
          default: 5000,
        },
      },
    }}
  />
</AppProvider>

#### Preserve Toast

A Toast component with preserve toast functionality retains the notification on the screen until explicitly dismissed, ensuring important messages or alerts remain visible and accessible to the user, even during subsequent interactions within the user interface.

<AppProvider>
  <CodePreview
    showArgsController={false}
    metaData={{
      code: `
        function Example() {
          const toast = useToast();
          return (
            <Button
              onPress={() => {
                toast.show({
                  placement: 'top',
                  duration: null,
                  render: ({ id }) => {
                    const toastId = "toast-" + id;
                    return (
                      <Toast bg='$error700' nativeID={toastId} p='$3'>
                        <Icon as={AlertTriangleIcon} color='$white' mt='$1' mr='$3' />
                        <VStack space='xs' flex={1}>
                        <ToastTitle color='$textLight50' >Account Security Alert</ToastTitle>
                        <ToastDescription color='$textLight50'>Your account password was recently changed.
                        If you did not authorize this change, please contact our support team immediately.
                        </ToastDescription>
                        </VStack>
                           <Pressable mt='$1' onPress={() => toast.close(id)}>
                        <Icon as={CloseIcon} color='$coolGray50' />
                       </Pressable>
                      </Toast>
                    );
                  },
                });
              }}
            >
              <ButtonText>Press Me</ButtonText>
            </Button>
          );
        };
      `,
      transformCode: (code) => {
        return transformedCode(code, 'function', 'Example');
      },
      scope: {
        View,
        Wrapper,
        Toast,
        ToastTitle,
        ToastDescription,
        useToast,
        Text,
        Icon,
        CloseIcon,
        Pressable,
        VStack,
        AlertTriangleIcon,
        Button,
        ButtonText,
      },
      argsType: {},
    }}
  />
</AppProvider>

## Unstyled

All the components in `gluestack-ui` are unstyled by default. To customize your UI using the extendedTheme, please refer to this [link](https://gluestack.io/ui/docs/theme-configuration/customizing-theme/eject-library). The import names of components serve as keys to customize each component.

## Spec Doc

Explore the comprehensive details of the Toast in this document, including its implementation details, checklist, and potential future additions. Dive into the thought process behind the component and gain insights into its development journey.

<iframe
  style={{
    borderRadius: '8px',
    border: ' 1px solid rgba(0, 0, 0, 0.1)',
    aspectRatio: 736 / 585,
  }}
  src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FNcXOxqKbdnGsLQNex3H76u%2F%25C2%25A0%25F0%259F%2593%259Agluestack-UI-handbook%3Fpage-id%3D5970%253A25350%26type%3Ddesign%26node-id%3D5970-27266%26viewport%3D1512%252C28%252C0.07%26t%3D2DA6PiUKnE8lxs6Y-1%26scaling%3Dcontain%26starting-point-node-id%3D5970%253A27266%26mode%3Ddesign"
  allowFullScreen
/>

<!--

### Advanced

We provide in-depth information on how to customize and extend the component's functionality to meet your needs. Below, we describe how to modify the component to suit your requirements.

### Customizing the Toast

We have a function called `createToast` which can be used to create a custom toast component. This function takes in a configuration object which contains the styled components that you want to use for the Input. You can refer [gluestack.io/style](/style/docs/getting-started/styled) on how to use styled components.

#### Usage

Default styling of all these components can be found in the `components/core/toast` file. For reference, you can view the [source code](https://github.com/gluestack/gluestack-ui/blob/main/packages/themed/src/components/Toast) of the styled `Toast` components.

```jsx
// import the styles
import {
  Root,
  Title,
  Description,
} from '../components/core/toast/styled-components';

// import the createToast function
import { createToast, createToastHook } from '@gluestack-ui/toast';

// Understanding the API
const Toast = createToast({
  Root,
  Title,
  Description,
});

const useToast = createToastHook(Toast);

// Using the toast component
export default () => {
  const toast = useToast();
  return (
    <Button
      {...props}
      onPress={() => {
        toast.show({
          placement: placement,
          render: ({ id }) => {
              const toastId = "toast-" + id;
              return (
                <Toast nativeID={toastId}>
                <ToastTitle>Hello World Toast {id}</ToastTitle>
              </Toast>
            );
          },
        });
      }}
    >
      <ButtonText>Press Me</ButtonText>
    </Button>
  );
};
```
-->
